﻿#region " LICENSE "
// DRILL - Dependency Resolution Interface Layer Library
// Copyright (c) 2008-2012 Wade A. Reynolds. All rights reserved.
// http://drill.codeplex.com/
// 
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
#endregion
using System.Configuration;
using Drill.Configuration.ConfigFile;
using Drill.Core;

namespace Drill.Configuration
{
	public interface IConfigurationHelper
	{
		/// <summary>
		/// Retrieves the specified config section from the default app or web config file.
		/// </summary>
		/// <returns>An instance of the <see cref="ConfigurationSection"/> class.</returns>
		T GetConfigSectionFromConfigFile<T>() where T : BaseConfigurationSection, new();

		/// <summary>
		/// Retrieves the specified config section from the specified config file.
		/// </summary>
		/// <param name="filename">The filename of the config file containing the secified config section.</param>
		/// <returns>An instance of the <see cref="ConfigurationSection"/> class.</returns>
		T GetConfigSectionFromConfigFile<T>(string filename) where T : BaseConfigurationSection, new();

		/// <summary>
		/// Retrieves the specified config section from the default app or web config file.
		/// </summary>
		/// <param name="configSectionName">The name of the config section to be retrieved.</param>
		/// <returns>An instance of the <see cref="ConfigurationSection"/> class.</returns>
		ConfigurationSection GetConfigSectionFromConfigFile(string configSectionName);

		/// <summary>
		/// Retrieves the specified config section from the specified config file.
		/// </summary>
		/// <param name="configSectionName">The name of the config section to be retrieved.</param>
		/// <param name="filename">The filename of the config file containing the secified config section.</param>
		/// <returns>An instance of the <see cref="ConfigurationSection"/> class.</returns>
		ConfigurationSection GetConfigSectionFromConfigFile(string configSectionName, string filename);

		///<summary>
		/// Loads the configuration from the specified config file.
		///</summary>
		///<param name="filename">The absolute path and file name of the config file to be loaded.</param>
		///<returns>An instance of the <see cref="Configuration" /> class loaded from the specified config file.</returns>
		System.Configuration.Configuration LoadConfigFile(string filename);

		/// <summary>
		/// Determines the absolute path of the specified file name.
		/// </summary>
		/// <param name="filename">
		///		The file name to be resolved. May be a relative path part or an absolute file name.
		/// </param>
		/// <returns>
		///		The absolute path of the file or null if the absolute path cannot be determined.
		/// </returns>
		/// <remarks>
		///		If the <paramref name="filename"/> is an absolute path, it is simply returned. 
		///		This method uses the configured implementations of the 
		///		<see cref="IRootPathProvider"/> interface to obtain a list of 
		///		valid root paths that may contain the configuration file.
		///		The first directory that contains the requested <paramref name="filename"/> 
		///		will be used to construct the absolute filename that is returned.
		///		<para>
		///			The <paramref name="filename"/> can be a simple file name or even a relative 
		///			path fragment that includes directory and file name information such as 
		///			<example>Config\SomeSpecialConfigDirectory\MyConfigFile.ext</example>.
		///		</para>
		/// </remarks>
		string FindAbsolutePath(string filename);
	}
}